DEFINITION MODULE OStrings; (* Franz Kronseder / 14.05.85 *)
                            (* last modified 30.05.85 *)
(* intended to supply a complete Set of String Manupulation Functions *)
(* for the Strings in the Macintosh operating system format.          *)

FROM SYSTEM IMPORT ADDRESS,ADR;
EXPORT QUALIFIED
        OStr7,OStr15,OStr31,OStr63,OStr127,OStr255,RefOStr,
        mkOStr,mkModStr,mkRef1,mkRef2,mkRefEmpty,
        msg,msgln,msgat,msgXY,errmsg,
        ReadOStr,askmsg,askmsgat,askmsgXY,WaitOK,askYesNo,
        OStrLen,OStrCh,OStrPos,OStrPat,OStrEqual,OStrCopy,OStrConcat,
        OStrOvWrStr,OStrInsCH,OStrDelCH,OStrInsStr,OStrDelStr;

(*** TYPE OString   = OPEN ARRAY OF CHAR ***)
(*** TYPE ModString = OPEN ARRAY OF CHAR ***)

TYPE OStr7   = ARRAY[0..  7] OF CHAR;
     OStr15  = ARRAY[0.. 15] OF CHAR;
     OStr31  = ARRAY[0.. 31] OF CHAR;
     OStr63  = ARRAY[0.. 63] OF CHAR;
     OStr127 = ARRAY[0..127] OF CHAR;
     OStr255 = ARRAY[0..255] OF CHAR;

     RefOStr = ADDRESS; (* reference to an OStr *)

(*----------------------------------------------------------*)

(**** here come procedures to convert between pascal ****)
(**** and modula format                              ****)
PROCEDURE mkOStr(VAR ModStr, OStr:ARRAY OF CHAR);
 (* convert a Modula String to an OStr *)

PROCEDURE mkModStr(VAR  OStr,ModStr:ARRAY OF CHAR);
 (* convert a OStr to a Modula String   *)

(**** here come procedures that return pointers to OStrings ****)

PROCEDURE mkRef1(VAR ModStr:ARRAY OF CHAR):RefOStr;
PROCEDURE mkRef2(VAR ModStr:ARRAY OF CHAR):RefOStr;

 (* the functions mkRef1 and mkRef2 each take a Modula string as argument *)
 (* and return a pointer to an equivalent OString.                        *)
 (* every new call to mkRef1/mkRef2 destroys the previous contents of     *)
 (* the corresponding OString.                                            *)
 (* the arguments are not modified.                                       *)
 (* the purpose of this procedures is to pass Modula-2 strings to         *)
 (* toolbox procedures (at most 2 at a time)                              *)
 (* Example:   SetWTitle (theWindow, mkRef1 ("MY WINDOW") );              *)
 (* the strings can be 127 characters long.                               *)

PROCEDURE mkRefEmpty():RefOStr;
 (* returns the address of the empty OString *)

(**** here come procedures to display  OStrings on the ****)
(**** screen                                           ****)

PROCEDURE msg(msgPtr:RefOStr);
 (* write the message, an OStr pointed to by msgPtr *)

PROCEDURE msgln(msgPtr:RefOStr);
 (* writeln the message, an OStr pointed to by msgPtr *)

PROCEDURE msgat(h,v:INTEGER;msgPtr:RefOStr);
 (* write the message at the position given in pixels *)

PROCEDURE msgXY(h,v:INTEGER;msgPtr:RefOStr);
 (* write the message at the position given in chars *)

PROCEDURE errmsg(msgPtr:RefOStr;fatal:BOOLEAN);
 (* tell User an Error Message; abort Program if fatal Flag *)

(*------------------------------------------------------------*)
(** here come procedures for String Input from User **)
PROCEDURE ReadOStr(msgPtr:RefOStr);

PROCEDURE askmsg(VAR prompt:ARRAY OF CHAR;msgPtr:RefOStr);
 (* write prompt, read a string, writeln *)
 (* ReadString a Pascalstring from the Console *)

PROCEDURE askmsgat(h,v:INTEGER;VAR prompt:ARRAY OF CHAR;msgPtr:RefOStr);
 (* MoveTo, write prompt, readstring, writeln *)

PROCEDURE askmsgXY(h,v:INTEGER;VAR prompt:ARRAY OF CHAR;msgPtr:RefOStr);
 (*ask the message at the position given in chars *)

PROCEDURE WaitOK;
 (* wait until user types in a char at the console *)

PROCEDURE askYesNo(VAR prompt:ARRAY OF CHAR):BOOLEAN;

(*------------------------------------------------------------*)
(* here come some functions about OStrings *)
PROCEDURE OStrLen(msgPtr:RefOStr):CARDINAL;
 (* returns the actual stringlength *)

PROCEDURE OStrCh(msgPtr:RefOStr;nth:CARDINAL):CHAR;
 (* returns the nth char in that string *)

PROCEDURE OStrPos(msgPtr:RefOStr;ch:CHAR):CARDINAL;
 (* returns the position of ch in that string, *)
 (* zero if not found *)

PROCEDURE OStrPat(pattern:RefOStr; object:RefOStr):CARDINAL;
 (* returns the position of the pattern string in the object string *)

PROCEDURE OStrEqual(s1,s2:RefOStr):BOOLEAN;
 (* tests if both strings have same size and chars *)

PROCEDURE OStrCopy(src,dest:RefOStr):RefOStr;
 (* copies OStrLen(src) chars from source to destination *)

PROCEDURE OStrConcat(src1,src2,dest:RefOStr):RefOStr;
 (* places the concatenation of the two source-strings *)
 (* at dest and returns a pointer to dest *)
PROCEDURE OStrOvWrStr(dest,substring:RefOStr; pos:CARDINAL):RefOStr;
 (* overwrite with substring *)

PROCEDURE OStrInsCH(dest:RefOStr;ch:CHAR;pos:CARDINAL):RefOStr;
 (* Insert a char in the string at a given position *)

PROCEDURE OStrDelCH(dest:RefOStr;ch:CHAR;pos:CARDINAL):RefOStr;
 (* Delete a char in the string at a given position *)

PROCEDURE OStrInsStr(dest,src:RefOStr;pos:CARDINAL):RefOStr;
 (* Insert a substring at given position *)

PROCEDURE OStrDelStr(dest,src:RefOStr;pos:CARDINAL):RefOStr;
 (* Delete a substring at given position *)


END OStrings.

(* An OString (or sometimes called 'Pascal String') is an array of   *)
(* char, maximum length 256 bytes, with ORD(byte 0) indicating the    *)
(* actual string length *)
